LIN Bus Adapter

The LIN Bus Adapter is a collection of tools that lets you develop and integrate tests and simulations involving communication over a LIN bus within the miniHIL platform.

The set of tools includes:

  • An LDF configuration editor with autocompletion, validation and navigation.

  • An LDF-to-eTrice model generator that automatically creates a ROOM classes representing the LIN nodes in the LDF configuration file.

  • Runtime and model support libraries that allow the generated ROOM LIN adapter actors to interact with a LIN bus.

The LIN LDF editor and generator is by default enabled in the miniHIL IDE, with no configuration necessary.

When you open any file within the MiniHilProject that has an ldf extension, it will be shown in the LDF editor. If the LDF file is located under the model-user directory, then whenever you save changes made to the LDF configuration file, the generator will be invoked by the IDE and the ROOM-based adapter model will be refreshed.

The lin generator is also part of the gradle build and it is integrated into the normal assemble process. If needed, you can invoke the generator separately: .\gradlew.bat generateLin. The gradle task generates room models for all files with the .ldf extension in the MiniHilProject/model-user folder as well as in all configured library projects.

Hardware

On the miniHIL board, the LIN Adapters use pins PD0 (RX) and PD1 (TX). These correspond to hardware UART4, with DMA2 streams 4 and 5. When a LIN adapter is enabled, UART4 is initialized in LIN mode (i.e. break detection enabled).

The RX and TX pins usually need to be connected to a LIN transceiver to communicate with a physical LIN bus.

Example

Consider this node definition from an LDF configuration file MiniHilProject/model-user/Example.ldf:

Example.ldf node definition 
Nodes {
  Master: Controller, 1 ms, 0 ms ;
  Slaves: Device1, Device2;
}

In this case a ROOM model file MiniHilProject/model-gen/lin/Example.room is generated. This ROOM model contains 3 LIN adapter actors: ALinAdapterExample_Controller, ALinAdapterExample_Device1, and ALinAdapterExample_Device2. See the Adapter Model Components section for more details.

CaGe Test - Mock LIN Node

Suppose that the DUT contains the Device1 and Device2 nodes, and you would like to write a CaGe test that can interact with the DUT as if it were a Controller node. In this case, you want to provide a "mock" of the Controller node. Therefore, the CaGe test interface will be:

conjugate ActorClass ALinAdapterExample_Controller

Alternatively, if additional ports are required by the test, you can define a port provider ActorClass which includes the conjugated lin adapter ports and reference the port provider in the CaGe test interface. After defining the CaGe test interface, an adapter actor can be connected directly to the cage test like so:

lin adapter

For details about interacting with the LIN adapter instance, see the API section.

API

The generated actors expose different functionality through different ports. A generated slave node adapter actor is controlled using two different protocols:

  • The generated PSignals[…​] protocol which allows to read and write lin signals from the lin bus image.

  • The PLinCtrl protocol is used to control the LIN slave process which is responsible to fill in frame content once a header is detected on the bus. (see busadapters.api.lin.PLinCtrl).

A generated master node adapter actor additionally exposes frame scheduling functionality:

  • The PLinCtrlScheduler protocol controls the LIN master process which is responsible for the generation of frame headers according to schedules defined in the LDF (see busadapters.api.lin.PLinCtrlScheduler).

Note The master node adapter must first be started via the PLinCtrl protocol in the same way as the slave node adapters, so that it can receive and process frames.

Usage Scenario Examples

Some examples of possible usages for the LDF generator include:

  • Simulation of a LIN node communicating with a DUT over a physical LIN bus.

  • Execution of CAGE tests that involve LIN communication with a DUT over a physical LIN bus.

  • Execution of CAGE tests that involve LIN communication over a simulated bus.

Sending and receiving diagnostic frames using cage

To send and receive diagnostic frames, first ensure that a schedule table is defined in the LDF configuration file which contains the frames to send, e.g.:

DiagMasterSlaveTable {
    MasterReq delay 20ms;
    SlaveResp delay 20ms;
}

Currently it is the users responsibility to synchronize setting the diagnostic data and running the diagnostic schedule. The following steps have to be executed to send and receive a diagnostic frame using the schedule defined above:

  1. Set the diagnostic data which should be send using the diagFrameSet message (PLinCtrl)

    • In the DLinDiagFrame DataClass set the type to ELinDiagFrameType_MasterReq.

  2. If the lin scheduler is currently active:

    1. Stop the currently running schedule using the runOnce or break message (PLinCtrlScheduler)

    2. Wait for the scheduleDone message

  3. Switch to the diagnostic schedule using the schedule message in PLinCtrlScheduler

    • Use the generated ELinScheduleTable<Node> enumeration to select the correct schedule.

  4. Run the diagnostic schedule once: runOnce

  5. Expect a diagFrameRecv message via the PLinCtrl protocol

Example: Sending and receiving diagnostic frames using CaGe 
/*
    The following ports connected to the master adapter are used:
    - linMasterCtrl (PLinCtrl)
    - linSchedulerCtrl (PLinCtrlScheduler)
*/

Step sendAndReceiveDiagFrame:
  action
    // initialize the master adapter
    linMasterCtrl.start
    // set the diagnostic frame data to send
    ``
  	  DLinDiagFrame diagData = {
  	    .type = ELinDiagFrameType_MasterReq,
  	    .data = { 0x1, 0x2, 0x5, 0xF1 }
      };
    ``
    linMasterCtrl.diagFrameSet(``&diagData``)
  action
    // make the scheduler stop once the end of the active schedule is reached
    linSchedulerCtrl.runOnce
  reaction
    // wait for currently active schedule to finish
    expect linSchedulerCtrl.scheduleDone(*)
  action
    // set the schedule to send and receive the diagnostic frames
    ``
      DLinScheduleState scheduleState = {
        .schedule = ELinScheduleMasterNode_DiagMasterSlaveTable,
        .pos = 0
      };
    ``
    linSchedulerCtrl.schedule(``&scheduleState``)
    // and run the schedule once
    linSchedulerCtrl.runOnce
  reaction
    expect linSchedulerCtrl.scheduleDone(*)
    expect linMasterCtrl.diagFrameRecv => [ data |
	    // validate the received data here
	]
;

Adapter Model Components

The LDF-to-eTrice generator creates a set of model components for each node defined in the .LDF file.

PSignals<LdfName>_<Node>

Represents the signals that are published and subscribed by a <Node>.

ALinAdapter<LdfName>_<Node>

A self-contained convenience actor that combines the Bus and SignalStore actors.

ALinSignalStore<LdfName>_<Node>

Maps raw LIN frames to and from ROOM signal representations for <Node>.

ALinBus<LdfName>_<Node>

Configures access to the LIN runtime driver for a <Node>. If the LIN node is a master, then the LIN node schedule table will also be configured.

For example, given this node definition from an LDF configuration file named Example.ldf:

Example.ldf node definition 
Nodes {
  Master: Controller, 1 ms, 0 ms ;
  Slaves: Device1, Device2;
}

the following model classes will be generated for the Controller node:

  • PSignalsExample_Controller

  • ALinAdapterExample_Controller

  • ALinBusExample_Controller

  • ALinSignalStoreExample_Controller

Similar sets of model classes will also be generated for the Device1 and Device2 nodes.

Note Currently you can only create one instance of each ALinAdapter actor in any given ROOM subsystem.